用户标签

一、应用场景

用户标签是提供给企业标记C端用户的功能。企业可以自定义用户标签，通过标签标注不同的用户，以做到统一的管理和运营。

  • 标注不同用户所拥有的标签。

  • 查看用户所拥有的全部标签。

二、功能说明

企业可以添加不同的用户标签，使用已添加的标签标注用户。

三、前提条件

无

四、关键流程

4.1 用户标签管理

流程说明：

  • 首先，B端成员使用账号密码登录到企业管理台　或者　云云对接系统使用平台访问授权秘钥登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
  • 其次，相应客户端使用物联网中台调用凭证发起对　用户标签的创建/更新/查询/删除以及列表　请求。
  • 再次，物联网中台接收到客户端相关请求，进行用户标签的持久化操作。
  • 最后，物联网中台根据不同请求为客户端返回不同的响应信息。

用户标签管理

4.2 用户标签标记用户

流程说明：

  • 首先，B端成员使用账号密码登录到企业管理台　或者　云云对接系统使用平台访问授权秘钥登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
  • 其次，相应客户端使用物联网中台调用凭证发起 查询用户拥有标签列表 或者 设置用户拥有标签　请求。
  • 再次，物联网中台接收到客户端相关请求，进行用户拥有标签的持久化操作。
  • 最后，物联网中台根据不同请求为客户端返回不同的响应信息。

用户标签标记用户

五、API列表

5.1 用户注册

5.1.1 创建用户标签

接口描述

企业成员在企业管理台用户创建用户标签，用于标记C端用户；用户标签名称企业下唯一，长度1-10，每个企业最多创建500个标签

请求方式

POST

请求地址

/v2/users/tag

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
name body true String 名称，不能重复，长度1-10
type body true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour body true String 标签颜色，RGB字符串

请求示例：

{
    "name": "黑名单",
    "type": 1,
    "colour": "FFFFFF"
}

返回参数说明

名称 必填 类型 备注
id true String 用户标签标识
name true String 名称，不能重复，长度1-10
type true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour true String 标签颜色，RGB字符串
create_time true String 创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’

返回示例：

{
    "id": "ds123546efd2ff",
    "create_time": "2019-12-16T16:00:00.000Z",
    "name": "黑名单",
    "type": 1,
    "colour": "FFFFFF"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001421 用户标签已存在
4001422 用户标签类型未知
4001423 用户标签超过限额

5.1.2 更新用户标签

接口描述

企业成员在企业管理台用户根据标识更新用户标签，用于标记C端用户；用户标签名称企业下唯一，长度1-10，每个企业最多创建500个标签

请求方式

PUT

请求地址

/v2/users/tag/{id}

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
id path true String 用户标签标识
name body false String 名称，不能重复，长度1-10
type body false Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour body false String 标签颜色，RGB字符串

请求示例：

{
    "name": "黑名单",
    "type": 1,
    "colour": "FFFFFF"
}

返回参数说明

名称 必填 类型 备注
id true String 用户标签标识
name true String 名称，不能重复，长度1-10
type true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour true String 标签颜色，RGB字符串
create_time true String 创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’

返回示例：

{
	"id": "ds123546efd2ff",
	"create_time": "2019-12-16T16:00:00.000Z",
	"name": "黑名单",
	"type": 1,
	"colour": "FFFFFF"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001421 用户标签已存在
4001422 用户标签类型未知
4001423 用户标签超过限额
4041108 用户标签不存在

5.1.3 查询用户标签

接口描述

企业成员在企业管理台用户根据标识查询用户标签；

请求方式

GET

请求地址

/v2/users/tag/{id}

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
id path true String 用户标签标识

请求示例：

{
}

返回参数说明

名称 必填 类型 备注
id true String 用户标签标识
name true String 名称，不能重复，长度1-10
type true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour true String 标签颜色，RGB字符串
create_time true String 创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’

返回示例：

{
	"id": "ds123546efd2ff",
	"create_time": "2019-12-16T16:00:00.000Z",
	"name": "黑名单",
	"type": 1,
	"colour": "FFFFFF"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041108 用户标签不存在

5.1.4 删除用户标签

接口描述

企业成员在企业管理台用户根据标识删除用户标签，同时取消被标记的用户；

请求方式

DELETE

请求地址

/v2/users/tag/{id}

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
id path true String 用户标签标识

请求示例：

{
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041108 用户标签不存在

5.1.5 获取用户标签列表

接口描述

企业成员根据条件查询用户标签列表，企业管理台用于查看展示

请求方式

POST

请求地址

/v2/users/tags

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
offset body false Int 偏移量
limit body false Int 查询量
sort body false Object 排序字段
query body false Object 查询条件，支持操作符有
$eq：等于
$gt：大于
$lt：小于
$gte：大等于
$lte：小等于
$ne：不等于
$nin：不包含，用于数组
$in：包含，用于数组
$like：模糊匹配，用于字符串
$all：全都在，用于数组

请求示例：

{
    "offset": 0,
    "limit": 10,
    "sort": {
        "name": "desc"
    },
    "query": {
        "id": {
            "$eq": "1256sdfsdf564"
        }
    }
}

返回参数说明

名称 必填 类型 备注
count true Int 用户标签总数
list true Array 用户标签列表
list.id true String 用户标签标识
list.name true String 名称，不能重复，长度1-10
list.type true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
list.colour true String 标签颜色，RGB字符串
list.create_time true String 创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.mark_users true Int 标签已标注的用户数

返回示例：

{
	"count": 1,
	"list": [{
		"id": "ds123546efd2ff",
		"create_time": "2019-12-16T16:00:00.000Z",
		"name": "黑名单",
		"type": 1,
		"colour": "FFFFFF",
		"mark_users": 10
	}]
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足

5.1.6 查询每个用户拥有的标签

接口描述

企业成员在企业管理台根据用户标识查询拥有的标签列表.

请求方式

POST

请求地址

/v2/users/tag-relations

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
user_ids body true Array 用户标识列表

请求示例：

{
    "user_ids": [15648954, 556415121]
}

返回参数说明

名称 必填 类型 备注
id true String 用户标签标识
name true String 名称，不能重复，长度1-10
type true Int 标签类型，枚举
1:黑名单
2:白名单
3: 灰名单
colour true String 标签颜色，RGB字符串
create_time true String 创建时间，格式如yyyy-MM-dd’T’HH:mm:ss.SS’Z’
user_id true Int 用户标识

返回示例：

[{
    "id": "1565sffedf123fsd",
    "name": "黑名单",
    "create_time": "2019-12-16T16:00:00.000Z",
    "type": 1,
    "colour": "FFFFFF",
    "user_id": 4532656
}]

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足

5.1.7 标注/取消用户拥有用户标签

接口描述

企业成员在企业管理台为用户标注标签或者取消标签

请求方式

PUT

请求地址

/v2/users/tag-relations

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Empower
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
opt body true Int 操作类型
1:标注
2:取消
user_ids body true Array 需要操作的用户标识列表，最多50个用户标识
tag_ids body true Array 需要操作的标签列表，最多50个标签标识

请求示例：

{
    "opt": 1,
    "user_ids": [1235645, 1234645],
    "tag_ids": ["15fdsfdsfdsf65", "15fdsfdsfdsf66"]
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041108 用户标签不存在
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题